hookable

What is hookable?

The 'hookable' npm package provides a way to create and manage hooks in JavaScript applications. Hooks are functions that can be registered and executed at certain points in your application, allowing for extensibility and customization.

What are hookable's main functionalities?

Creating and Registering Hooks

This feature allows you to create and register hooks. In the example, a hook named 'myHook' is created and a function is registered to it. When 'myHook' is called, the registered function is executed.

const { Hookable } = require('hookable');
const hooks = new Hookable();

hooks.hook('myHook', async () => {
  console.log('Hook executed!');
});

hooks.callHook('myHook');

Adding Multiple Handlers to a Hook

This feature allows you to add multiple handlers to a single hook. In the example, two handlers are registered to 'myHook'. When 'myHook' is called, both handlers are executed in the order they were registered.

const { Hookable } = require('hookable');
const hooks = new Hookable();

hooks.hook('myHook', async () => {
  console.log('First handler executed!');
});

hooks.hook('myHook', async () => {
  console.log('Second handler executed!');
});

hooks.callHook('myHook');

Passing Arguments to Hooks

This feature allows you to pass arguments to hooks. In the example, a message is passed to 'myHook' when it is called, and the registered handler logs the message to the console.

const { Hookable } = require('hookable');
const hooks = new Hookable();

hooks.hook('myHook', async (message) => {
  console.log(message);
});

hooks.callHook('myHook', 'Hello, world!');

Handling Errors in Hooks

This feature allows you to handle errors that occur in hooks. In the example, an error is thrown in the registered handler for 'myHook'. The error is caught and logged to the console when 'myHook' is called.

const { Hookable } = require('hookable');
const hooks = new Hookable();

hooks.hook('myHook', async () => {
  throw new Error('Something went wrong!');
});

hooks.callHook('myHook').catch(err => {
  console.error(err.message);
});

Other packages similar to hookable

tapable

Tapable is a similar package that provides a way to create and manage hooks. It is used internally by webpack to allow plugins to extend its functionality. Compared to hookable, tapable offers a more extensive API and is designed to handle more complex use cases.

mitt

Mitt is a tiny functional event emitter. While it is not specifically designed for hooks, it can be used to achieve similar functionality by emitting and listening to events. Mitt is simpler and more lightweight compared to hookable.

eventemitter3

EventEmitter3 is a high-performance event emitter. Like mitt, it is not specifically designed for hooks but can be used to create and manage hooks by emitting and listening to events. EventEmitter3 is known for its performance and is more feature-rich compared to mitt.

README

Hookable

Awaitable hooks for Node.js and Browser

Install

Using yarn:

yarn add hookable

Using npm:

npm install hookable

Usage

Extend your base class from Hookable:

import Hookable from 'hookable'

export default class Foo extends Hookable {
  constructor() {
    // Call to parent to initialize
    super()
    // Initialize Hookable with custom logger
    // super(consola)
  }

  async someFunction() {
    // Call and wait for `hook1` hooks (if any) sequential
    await this.callHook('hook1')
  }
}

Inside plugins, register for any hook:

const lib = newFooLib()

// Register a handler for `hook2`
lib.hook('hook2', async () => { /* ... */ })

// Register multiply handlers at once
lib.addHooks({
  hook1: async () => { /* ... */ },
  hook2: [ /* can be also an array */ ]
})

Unregistering hooks:

const lib = newFooLib()

const hook0 = async () => { /* ... */ }
const hook1 = async () => { /* ... */ }
const hook2 = async () => { /* ... */ }

// The hook() method returns an "unregister" function
const unregisterHook0 = lib.hook('hook0', hook0)
const unregisterHooks1and2 lib.addHooks({ hook1, hook2 })

/* ... */

unregisterHook0()
unregisterHooks1and2()

// or

lib.removeHooks({ hook0, hook1 })
lib.removeHook('hook2', hook2)

Triggering a hook handler once:

const lib = newFooLib()

const unregister = lib.hook('hook0', async () => {
  // Unregister as soon as the hook is executed
  unregister()

  /* ... */
})

Hookable class

constructor(logger)

Custom logger. Default logger is console but you can use your own or consola.

It should be an object implementing following functions:

• warn
• error
• fatal (optional)

hook (name, fn)

Register a handler for a specific hook. fn must be a function.

Returns an unregister function that, when called, will remove the registered handler.

hookOnce (name, fn)

Similar to hook but unregisters hook once called.

Returns an unregister function that, when called, will remove the registered handler before first call.

addHooks(configHooks)

Flatten and register hooks object.

Example:

hookable.addHooks({
  test: {
    before: () => {},
    after: () => {}
  }
})

This registers test:before and test:after hooks at bulk.

Returns an unregister function that, when called, will remove all the registered handlers.

async callHook (name, ...args)

Used by class itself to sequentially call handlers of a specific hook.

deprecateHook (old, name)

Deprecate hook called old in favor of name hook.

deprecateHooks (deprecatedHooks)

Deprecate all hooks from an object (keys are old and values or newer ones).

removeHook (name, fn)

Remove a particular hook handler, if the fn handler is present.

removeHooks (configHooks)

Remove multiple hook handlers.

Example:

const handler = async () => { /* ... */ }

hookable.hook('test:before', handler)
hookable.addHooks({ test: { after: handler } })

// ...

hookable.removeHooks({
  test: {
    before: handler,
    after: handler
  }
})

Credits

Extracted from Nuxt.js hooks system

Original author Sébastien Chopin

Thanks to Joe Paice for donating hookable package name

License

MIT - Made with 💖 by Nuxt.js team!

Changelog

4.4.1 (2021-02-26)

Bug Fixes

• avoid creating extra wrapper when merging hooks (790c1c4)